import TabItem from "@theme/TabItem";
import Tabs from "@theme/Tabs";

# Recordings

There are two types of recordings in Viseron, event recordings and continuous recordings.

## Event recordings

Event recordings are triggered by events such as motion detection or object detection. The recordings are saved to disk and can be viewed in the web interface on the `Events` tab on the `Events` page.

### Configuration

The config option `trigger_event_recording: true` instructs Viseron to start recording when the event is detected.

Example configuration to record when detecting a person:

```yaml title="/config/config.yaml"
darknet: # or any other object detector component
  object_detector:
    cameras:
      camera_one:
        fps: 1
        scan_on_motion_only: false
        labels:
          - label: person
            confidence: 0.7
            // highlight-start
            trigger_event_recording: true
            // highlight-end
```

:::info

By default, event recordings are stored for 7 days. This can be changed by setting [retention rules](#retention-rules).

:::

:::info

The `trigger_event_recording` option is only available for motion and object detectors.

:::

### Viewing event recordings

To view event recordings, go to the `Events` tab on the `Events` page. Here you can see all events that have been detected and recorded.
Clicking on one will seek to the time of the event.

:::info

If you see a snapshot instead of a video when you click the event, it means that the video is no longer available. Tune your retention rules to keep the recordings longer.

:::

#### Filters

Various types of filtering can be applied:

- Any number of cameras can be selected by clicking on the Cameras button in the bottom right.

  <details>
    <summary>Cameras Button (highlighted in green)</summary>
    <img
      src="/img/screenshots/Viseron-Events-camera-button.png"
      alt-text="Cameras Button"
      width={700}
    />
  </details>

- You can filter by date by clicking on the date button in the bottom right.

  <details>
    <summary>Date Button (highlighted in green)</summary>
    <img
      src="/img/screenshots/Viseron-Events-date-button.png"
      alt-text="Date Button"
      width={700}
    />
  </details>

- You can also filter by event type, such as motion or object detection. The filter menu is located next to the Events/Timeline tab selector.
  <details>
    <summary>Event type filter demo</summary>
    <video
      controls
      muted
      autoPlay
      loop
      style={{ maxWidth: 700, width: "100%" }}
    >
      <source
        src="/img/videos/Viseron-Events-filter-event-type.mp4"
        type="video/mp4"
      />
      Your browser does not support the video tag.
    </video>
  </details>

#### Grouping

Events from the same camera that are within 2 minutes of each other are grouped together.
If you want to group adjacent events from different cameras, you can select the `Group Cameras` option in the filter menu.
The filter menu is located next to the Events/Timeline tab selector.

## Continuous recordings

If configured, continuous recordings are always running and stored to disk. The recordings can be viewed in the web interface on the `Timeline` tab on the `Events` page.

### Configuration

To enable continuous recordings, all you need to do is set [retention rules](#retention-rules) since the default value of `continuous_recording` is `true`.

:::info

There are several ways to set retention rules. See the [retention rules section](#retention-rules) for more information.

:::

Example configuration to record continuously:

```yaml title="/config/config.yaml"
ffmpeg: # or any other camera component
  camera:
    camera_one:
      name: Camera 1
      host: !secret camera_one_host
      path: /Streaming/Channels/101/
      username: !secret camera_one_username
      password: !secret camera_one_password
      recorder:
        // highlight-start
        continuous_recording: true  # Not needed since it is the default, included for clarity
        continuous:  # Example of setting a max size of 10 GB for this individual camera
          max_size:
            gb: 10
        // highlight-end
```

### Viewing continuous recordings

To view continuous recordings, go to the `Timeline` tab on the `Events` page. Here you can see all continuous recordings that have been recorded.

To seek to a specific point in time, you simply click on the timeline. The timeline will show you the recordings for all cameras that are selected, if video is available.

The `Activity Line` visually represents the activity detected by the cameras over time, helping to quickly identify periods of interest.

<details>
  <summary>Activity Line explanation</summary>
  <img
    src="/img/screenshots/Viseron-Events-activity-line.png"
    alt-text="Activity Line"
    width={700}
  />
  <p>Activity Line colors:</p>
  - **Slim dark blue**: No activity detected, and recorded video is **not** available.
  - **Thick light blue**: No activity detected, but recorded video is available.
  - **Thick pink**: Motion detected.
  - **Thick green**: Event recording is available.

</details>

#### Filters

The same [filters as for event recordings](#filters) can be applied to continuous recordings.

## Retention rules

There are a number of ways to control the retention of recordings.

:::tip

Storage tiers can be used to move recordings to different storage locations based on age or size.

See the [storage component tiers documentation](/components-explorer/components/storage#tiers) for more information.

:::

### Setting retention rules for all cameras

To use the same retention rules for all cameras it is recommended to use the [storage component](/components-explorer/components/storage).

:::warning

Size based retention rules are calculated **per camera**, meaning that if you have 2 cameras and set a `max_size` of 1 GB, each camera can store 1 GB of recordings for a total of 2 GB.

:::

Example configuration to set retention rules for all cameras:

```yaml title="/config/config.yaml"
storage:
  recorder:
    tiers:
      - path: / # Video segments will be stored in the /segments directory
        events:
          max_age:
            days: 14
        continuous:
          max_size:
            gb: 10
```

:::tip

This will enable continuous recordings for all cameras. If you want to disable continuous recordings for a specific camera, you can set `continuous_recording: false` in the cameras `recorder` configuration.

:::

### Setting retention rules for a specific camera

You can set retention rules for a specific camera by adding the `events`, `continuous` or `storage` key to the camera config.

Example configuration to set retention rules for a specific camera:

<Tabs groupId="retention-type">
<TabItem value="events" label="Event">

```yaml title="/config/config.yaml"
ffmpeg: # or any other camera component
  camera:
    camera_one:
      name: Camera 1
      host: !secret camera_one_host
      path: /Streaming/Channels/101/
      username: !secret camera_one_username
      password: !secret camera_one_password
      // highlight-start
      recorder: # Store only events for 14 days
        events:
          max_age:
            days: 14
      // highlight-end
```

</TabItem>
<TabItem value="continuous" label="Continuous">

```yaml title="/config/config.yaml"
ffmpeg: # or any other camera component
  camera:
    camera_one:
      name: Camera 1
      host: !secret camera_one_host
      path: /Streaming/Channels/101/
      username: !secret camera_one_username
      password: !secret camera_one_password
      // highlight-start
      recorder: # Store 10gb of continuous recordings
        continuous:
          max_size:
            gb: 10
      // highlight-end
```

</TabItem>

<TabItem value="storage" label="Storage">

```yaml title="/config/config.yaml"
ffmpeg: # or any other camera component
  camera:
    camera_one:
      name: Camera 1
      host: !secret camera_one_host
      path: /Streaming/Channels/101/
      username: !secret camera_one_username
      password: !secret camera_one_password
      // highlight-start
      storage: # Store events for 14 days and 10gb of continuous recordings
        recorder:
          tiers:
            - path: / # Video segments will be stored in the /segments directory
              events:
                max_age:
                  days: 14
              continuous:
                max_size:
                  gb: 10
      // highlight-end
```

</TabItem>
</Tabs>

## File format

The recordings are saved in short `.m4s` (aka `fMP4` or `fragmented MP4`) segments.

In the web interface the recordings are played back using [HLS](https://developer.apple.com/streaming/) and the `hls.js` library.
When you request a recording in the web interface, the server API will generate an HLS playlist and serve the segments to the client.

:::warning

The recordings are not playable on their own since they are fragmented. If you want to play the recordings outside of the web interface you will need to [download the recordings](#downloading-recordings).

Alternatively you can point your media player to the HLS playlist URL (the same used by the web interface), but this is currently not documented.

:::

## Downloading recordings

From the web interface you can download recordings to an `.mp4` file.

### Downloading an event recording

To download an event recording, you use the `Download Recording` button in the event details popup on the `Events` tab. It will download the selected event to an `.mp4` file.

<img
  src="/img/screenshots/Viseron-Events-download-recording.png"
  alt-text="Download Recording"
  width={700}
/>

### Downloading a continuous recording

By using the `Download` button on the `Events` or `Timeline` tab you can download a continuous recording. It will download the selected time range to an `.mp4` file.

:::info

If you have multiple cameras selected, one file per camera will be downloaded.

:::

<video controls muted autoPlay loop style={{ maxWidth: 700, width: "100%" }}>
  <source
    src="/img/videos/Viseron-Events-download-timespan.mp4"
    type="video/mp4"
  />
  Your browser does not support the video tag.
</video>

## Create MP4 files for all event recordings

If you want to create `.mp4` files for all event recordings you can use the `create_event_clip` configuration option.

```yaml title="/config/config.yaml"
ffmpeg: # or any other camera component
  camera:
    camera_one:
      name: Camera 1
      host: !secret camera_one_host
      path: /Streaming/Channels/101/
      username: !secret camera_one_username
      password: !secret camera_one_password
      // highlight-start
      recorder:
        create_event_clip: true
      // highlight-end
```

:::warning

This will create `.mp4` files for all event recordings, which will be stored in addition to the `.m4s` files.

THe `.mp4` files will be created in the `/event_clips` directory, unless you have set a different path in the [storage component](/components-explorer/components/storage).

:::

## Events page query parameters

The `Events` page supports a number of query parameters to control the behavior of the page.

The following query parameters are supported:

- `tab`: The tab to show. This can be `events` or `timeline`.
- `camera`: The camera identifier of the camera to show.
- `date`: The date to show, in the format `YYYY-MM-DD`.
- `timestamp`: The timestamp to seek to. This is a Unix timestamp in seconds.

Example URL to show the timeline for camera `camera_one` and seek to the timestamp `1745001300`:

```shell
http://localhost:8888/#/events?tab=timeline&camera=camera_one&timestamp=1745001300
```
